Skip to main content

Filter and Sort Syntax

Many adapters in the JS libraries implement filtered query functions. These functions take a GenericSearchOptions parameter. The GenericSearchOptions object contains filter and sort properties, which are string arrays. To learn about the format of the filter and sort strings, read the rest of this guide.

Sort​

A sort-parameter array must contain field names optionally preceded by a + (for ascending) or a - (for descending). If the + or - is omitted, the default is ascending.

example

["+name", "-created"] means that we are sorting by name ascending and then by created descending.

Filter​

A filter-parameter array must contain strings in the format <field><operator><value> or a FilterGroup object.

By default, the AND logical operator is applied to the filter conditions. However, you can force the search function to apply the OR operator with boolean groups.

Field​

By default, the field is a property of the entity you are searching for.

To search on properties of joined entities, you can use dot-notation in the field names. For example, to search for all runs that have a variable called score with a value of 90 or higher, add var.score>=90 to the filter string array in the parameters of the run adapter's query() function.

Operator​

  • <: less than. Used only with numbers.
  • <=: less than or equal to. Used only with numbers.
  • =: equal to. Case-insensitive. No wildcards.
  • >=: greater than or equal to. Used only with numbers.
  • >: greater than. Used only with numbers.
  • !=: not equal to. Case-insensitive. No wildcards.
  • *=: exists. Use this operator with true or false to check that a field has a value (is not null). For example, a search for runs with filter=var.certified*=true returns runs that have a non-null variable named certified.
  • ~=: like. You can use wildcards here. Begin and/or end the value with an *, e.g., startswith*, *endswith, *contains*.
  • ^=: not like. Similarly used with wildcards.
  • |=: in. Provide a list of values separated with a |, e.g., 1|2|3 or hello|goodbye.

Value​

Values are interpreted by the pattern.

example

["run.hidden=false", "var.certified*=true"] means that we are searching for runs where the 'hidden' attribute is false and that have a variable named certified that is true.

Boolean groups​

For a boolean search, pass a FilterGroup object in the filter param with the type property set to 'and' or 'or'. The boolean groups can be nested.

Taxonomy groups​

For a taxonomy search, pass a FilterGroup object in the filter param with the type property set to 'taxonomy'.